home *** CD-ROM | disk | FTP | other *** search
/ The PC-SIG Library 9 / The PC-SIG Library on CD ROM - Ninth Edition.iso / 801_900 / DISK0859 / DISK0859.ZIP / DOC / UTILITY.DOC < prev   
Text File  |  1988-01-06  |  18KB  |  352 lines
  1.  
  2. UTILITY.DOC PC/370 utility documentation
  3.  
  4. A.  Summary
  5.  
  6.     1.  SEE.ALC - this utility will support full screen editing of an
  7.         ASCII text file.  The size of the file is only limited by the
  8.         amount of MS-DOS memory available (up to 640K less MS-DOS and
  9.         PC/370).  The program is modeled after the TURBO PASCAL full
  10.         screen editor with compatible commands.  In addition to the
  11.         expanded memory support,  SEE supports full color selection,
  12.         character graphics, and session emulation.
  13.  
  14.     2.  PRINTDOC.ALC - this utility will read an ASCII text file and
  15.         print it on the standard printer device with headings and page
  16.         numbers set by standard ALC TITLE, EJECT, and SPACE commands.
  17.  
  18.     3.  T370.ALC - this utility reads A370 relocatable object files
  19.         which are in compressed bit stream format and creates standard
  20.         IBM 370 linkage editor input in standard 80 byte fixed record
  21.         format with ESD, TXT, RLD, and END type records.  This utility
  22.         also has option to generate ascii hex listing file if desired.
  23.         The 370 object files have a suffix of .370 and the listing
  24.         file has a suffix for .HEX.
  25.  
  26. To run demo of utility programs, execute BAT\RUNUTIL.BAT.  To rebuild
  27. executable utility modules from source run BAT\BLDUTIL.BAT.
  28.  
  29. B. SEE - Screen Editor and Emulator Documentation
  30.  
  31. SEE.ALC is a full screen ASCII text editor for PC's with MS-DOS 2.0+
  32. and at least 256k.  SEE is designed to be keystroke compatible with
  33. both PFS:WRITE and the TURBO PASCAL (ie WORDSTAR like) editors.  SEE
  34. supports text files up to 512k on a 640k system.  Note SEE.ALC itself
  35. is about 90k which some editors can't handle.  To conserve space SEE
  36. strips trailing blanks from each line of text, and replaces 9 leading
  37. blanks with a single tab character. Each line is terminated with a
  38. carriage return and line feed.
  39.  
  40. SEE also supports session emulation by optionally creating a file
  41. (.KSF) with all of the session's keystrokes which can be replayed to
  42. emulate the session with full color control.  SEE also supports line
  43. and block drawing with graphic characters in full color.
  44.  
  45. The distribution diskettes or ARC file contains SEE.COM which can be
  46. used to edit the source code UTIL\SEE.ALC.  TO edit an existing ASCII
  47. text file:
  48.  
  49.   A>SEE file1
  50.  
  51. E370R42.EXE is dynamically loaded by SEE.COM to execute the 370 code
  52. so it must be accessible on the current path as SEE.COM.  If you wish
  53. to run SEE using the emulator on a separate directory, you can use
  54. DEBUG to insert path in front of emulator name at X'140' in SEE.COM,
  55. or you can make the emulator resident by directly executing it.
  56. The default file type is ALC.  (Note with PC/370 you can change the
  57. default in SEE.ALC and reassemble and link it in about 90 seconds on a
  58. standard PC.)  If the file doesn't exist, it will create an empty file
  59. ready for editing.  If the file does exist, it will be renamed
  60. file1.BAK before saving the new file if it is changed.  Be sure there
  61. is room on the same disk for both the new file and the backup file
  62. before spending a lot of time editing a file.  Note SEE.ALC itself
  63. requires at least 110k free space before you can save it.
  64.  
  65. To capture all the keystrokes in a session for replay later, type:
  66.  
  67.   A>SEE file1 file2
  68.  
  69. The default file type for file2 is KSF.  If file2 does not exist, it
  70. will be created with all the keystrokes entered during the session
  71. which edits file1.  If file2 already exists, SEE will use it as the
  72. keyboard input to emulate the original session.  Note two special keys
  73. act different in live editing versus emulation.  ALT-F1 key causes
  74. emulation to stop until a real key is entered.  ALT-F2 key causes a 1
  75. second wait in emulation mode to slow it down for visual effects.
  76. Additional controls could be easily added to SEE.
  77.  
  78. SEE is designed to be fast and easy to use.  To change a drive
  79. specification in an autoexec.bat file a sequence of less than 25
  80. characters including the filename may be required.  For example,
  81. assuming autoexec.bat contains:
  82.  
  83. RECORD/COLUMN  1...5...10...15...20
  84.   1            ver
  85.   2            astclock
  86.   3            c:
  87.   4            123
  88.  
  89. The following keystrokes would change drive c to drive a:
  90.  
  91. keystrokes  ascii characters            comments
  92.  
  93.   1-19      see autoexec.bat[enter]   start up SEE and display text
  94.  20-21      [arrow down][arrow down]    move down to third line
  95.   22        a                           replace c with a
  96.   23        [esc]                       rename old file and save new
  97.   file
  98.  
  99. To learn the keystrokes available with SEE, use F1 and F2 to display
  100. help screens.  After reading help screens type any character to return
  101. to text display.
  102.  
  103. To see the capability of SEE and to verify that the version you have
  104. is working correctly on your system, run the batch file RUNUTIL.BAT.
  105. This file executes the following emulation sessions:
  106.  
  107.   1.  DEMOSEE1.KSF - test both native and alternate keys as defined on
  108.                      F2.
  109.   2.  DEMOSEE2.KSF - test full color character graphics by drawing
  110.                      colored organizational chart boxes and a full
  111.                      color U.S.  flag with blinking stars. Press enter
  112.                      to end session.
  113.  
  114. One of the unique features of SEE is that the entire 370 assembler
  115. source code is being distributed along with the object code.  Because
  116. of this, the SEE editor can be customized as required.  The SEE.ALC
  117. source program is about 3000 lines and requires no external
  118. subroutines.  On a RAM disk, it assembles in about 60 seconds via the
  119. command A370 SEE.  The link edit takes another 10 seconds via the
  120. command L370 SEE.  A listing of the source can be generated via the
  121. command A370 SEE/L if you have a hard disk.  The listing is too big to
  122. fit on a 360k floppy disk.
  123.  
  124. SEE has several special keys which may need additional explanation.
  125. The ALT-F3 key enters PC/370 debug mode where you can display the 370
  126. registers via the R command, dump memory via the D command, trace
  127. instructions, etc.  To return to the SEE editor, type Q.  Since the
  128. default is to kill all trace ids and disable the PC/370 interactive
  129. debug interrupt, you must either link SEE with the debug option D, or
  130. press a key during loading of the SEE program to get into PC/370 debug
  131. at the beginning of SEE where you can select ids to save and trace.
  132.  
  133. The ALT-F4 key toggles an internal audit mode which was very useful
  134. during debugging and may be useful to others making changes to SEE.
  135. In audit mode the critical pointers and control blocks are verified
  136. for consistency after each operation that modifies them.  For large
  137. text files, these audits may take several seconds so be patient.  Via
  138. the audit mode, data corruption can be detected immediately after it
  139. occurs rather than later such as when a save is attempted.  The
  140. following block diagram shows the critical blocks and their
  141. relationships:
  142.  
  143.  ******************************************************************
  144.  * MS-DOS   64k segment                                           *
  145.  ******************************************************************
  146.  * SEE.COM  512k segment (code and data in 370 address space)     *
  147.  *                                                                *
  148.  *       SCB screen control block                                 *
  149.  *      ************************* <<<<< ASCB pointer to screen    *
  150.  *   X>>*SCBADDR DS A addr LB   *       control block with 25     *
  151.  *   ^  *SCBPREV DS A prev LB   *       lines of text             *
  152.  *   ^  *SCBNEXT DS A next LB   *                                 *
  153.  *   ^  *SCBLINE DS CL80 text   *                                 *
  154.  *   ^  ************************* <<<<< R5 relative index to      *
  155.  *   ^  *SCBADDR DS A addr LB   *       current row in ASCB       *
  156.  *   ^  *SCBPREV DS A prev LB   *       times X'100'              *
  157.  *   ^  *SCBNEXT DS A next LB   *       (X'0000' to X'1700')      *
  158.  *   ^  *SCBLINE DS CL80 text   *                                 *
  159.  *   ^  *************************       R6 relative column (0-79) *
  160.  *   ^                                  R7 address of SCB for row *
  161.  *   ^                                                            *
  162.  *   ^                         GLBLAST  DS A last    LB >>>>>>>X  *
  163.  *   X<<<<<<<<<<<<<<<<<<<<<<<< GLBCUR   DS A current LB >>>>>X v  *
  164.  *    (matches SCBADDR for     GLBFIRST DS A first   LB >>>> v v  *
  165.  *     row 0 at all times)                                 v v v  *
  166.  *                                                         v v v  *
  167.  *                                                         v v v  *
  168.  *  (Dynamic memory allocated via SVC 10)                  v v v  *
  169.  *                                                         v v v  *
  170.  *    LB line control block                                v v v  *
  171.  *    ***************************                          v v v  *
  172.  * 0  * LBPREV DS A prev LB     *<<<<<<<<<<<<<<<<<<<<<<<<<<X v v  *
  173.  * X<<* LBNEXT DS A next LB     *                            v v  *
  174.  * v  * LBLINE DS CL80 text     *                            v v  *
  175.  * v  ***************************                            v v  *
  176.  * v      ^                                                  v v  *
  177.  * v      ^                                                  v v  *
  178.  * X>>***************************                            v v  *
  179.  *    * LBPREV DS A prev LB     *<<<<<<<<<<<<<<<<<<<<<<<<<<<<X v  *
  180.  * X<X* LBNEXT DS A next LB     *                              v  *
  181.  * v  * LBLINE DS CL80 text     *                              v  *
  182.  * v  ***************************                              v  *
  183.  * v      ^                                                    v  *
  184.  * v      ^                                                    v  *
  185.  * X>>***************************                              v  *
  186.  *    * LBPREV DS A prev LB     *<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<X  *
  187.  * 0  * LBNEXT DS A next LB     *                                 *
  188.  *    * LBLINE DS CL80 text     *                                 *
  189.  *    ***************************                                 *
  190.  *                                                                *
  191.  *    (note lower right number on status line is ratio of         *
  192.  *     active LB's to maximum LB's which will fit in extended     *
  193.  *     memory. AFREELB pointer maintains queue of unused LB's.)   *
  194.  *                                                                *
  195.  ******************************************************************
  196.  * E370R40.EXE PC/370 emulator loaded in high 64k segment         *
  197.  ******************************************************************
  198.  
  199. The key things that are verified by the audit mode routines are as
  200. follows:
  201.  
  202.   1.  The row (R5) and column (R6) relative pointers are within valid
  203.       range.
  204.   2.  The SCB address (R7) corresponds to current relative row (R5).
  205.   3.  The SCBADDR in row zero matches GLBCUR.
  206.   4.  The SCBPREV in each SCB matches SCBNEXT in previous SCB etc.
  207.   5.  Starting with LB at GLBFIRST, verify forward and backward chains
  208.       for all LB's in extended memory.  The total LB count is also
  209.       verified.
  210.  
  211. Do not leave audit mode on for normal editing since it significantly
  212. slows down the editor.
  213.  
  214. The label (F5), duplicate (F6), and delete key (del) all work
  215. together.  When ever a block is active, the BLK indicator is on.  Be
  216. sure to turn the block indicator off via F5, F6, or delete key.  If
  217. the block indicator is not off and  the (del) key is hit to delete a
  218. character, it will delete the block instead.  Note since the box
  219. graphics mode indicator shares the same space on the status line,
  220. turning on graphics will turn off the block indicator.
  221.  
  222. The search (F7) key will search for up to a 15 character key.  Use F8
  223. to repeat search.  If a replacement key is specified, it will only be
  224. replaced if it fits on current line.  Search can be interrupted by any
  225. key.  The current line number is updated every 100 lines during
  226. search.
  227.  
  228. The color selection key (F9) is tricky but powerful.  The attribute
  229. byte shown on the message line consists of four fields; the blink bit,
  230. the background color bits (RGB), the intensity bit, and the foreground
  231. color bits (RGB).  The default attribute is set to B'00010111' or
  232. X'17' which can be interpreted as no blink, no red background, no
  233. green background, blue background, no intensity, and red, green, and
  234. blue foreground (ie white foreground).  This is the PFS:WRITE default.
  235. The TURBO PASCAL editor default is yellow on black B'00001110' or
  236. X'0E'.  The attribute can be entered as a two digit hex number or the
  237. arrows can be used to step through all the possible color and blink
  238. combinations (all 256 of them).  Once the desired attribute is
  239. selected, press enter to return to the screen with the new attribute.
  240. Note that unfortunately the attributes of each character are not
  241. stored in the file and when the screen is erased and updated again,
  242. individual character attributes used on the screen are lost.  However,
  243. the emulator option allows recreation of any screen with all the
  244. colors used during the original session.  This capability can be used
  245. to generate full color screen dialogs.
  246.  
  247. In addition to color, the box graphics or line graphics capability
  248. allows creation of screens with organization charts and line diagrams
  249. such as the one above.  I did not use color and I selected printable
  250. characters via SHFT-F10 in order for this file to be printable on any
  251. ASCII printer.  The default box graphic characters when F10 is turned
  252. on is double line graphic characters which look neat on the screen but
  253. can't be printed on many printers.  When F10 is pressed, the BOX
  254. indicator comes on and the insert mode is turned off.  In BOX mode,
  255. the arrows allow drawing of boxes and lines with correct corners based
  256. on the current and next direction of arrows.  With a little practice,
  257. it is easy to draw things and to add color to highlight different
  258. parts.  However, the color is lost unless the keystroke file is being
  259. created during the session.  Note in BOX mode, keystrokes are not
  260. queued up as they are in normal text mode.  This is to prevent
  261. overshooting the end of a line when holding down one of the arrow
  262. keys.
  263.  
  264. The status line contains the following fields:
  265.  
  266.   1.  STATMSG  - 20 character message field used to display the
  267.                  current function and to echo requested input.
  268.   2.  STATFILE - name of the file being edited with path (15 char.
  269.                  shown).
  270.   3.  STATREC  - current line number.
  271.   4.  STATCOL  - current cursor column
  272.   5.  STATCAP  - caps key indicator
  273.   6.  STATINS  - insert mode indicator (SEE always starts with INS
  274.                  off)
  275.   7.  STATNUM  - numeric mode indicator
  276.   8.  STATBLK  - labeled block mode indicator / box graphics mode
  277.                  indicator
  278.   9.  STATPCT  - percent utilization of available memory
  279.  
  280. As a starting point for anyone who wishes to add a new key function,
  281. the following minimum steps are required:
  282.  
  283.   1.  Overlay byte in KEYTAB which corresponds to the value of the new
  284.       key with an index to the corresponding address in KRTAB.
  285.       (All ASCII keys are in the range 0-127, and all extended keys
  286.       are mapped into 128-255 by forcing the high order bit on.)
  287.       Since the index values are multiples of 4, up to 63 keys can be
  288.       handled with this scheme.
  289.  
  290.   2.  Insert address constant in KRTAB which points to the actual key
  291.       routine.
  292.  
  293.   3.  Code the key routine with the following assumptions:
  294.  
  295.       a.  R14 has return address (You can use KRSV14 to save it.)
  296.       b.  R5  has relative row times X'100'.
  297.       c.  R6  has relative column.
  298.       d.  R7  has address of SCB corresponding to current row.
  299.       e.  GLBCUR    has extended memory address of LB for row 0 on
  300.           screen.
  301.       f.  GLBLAST   has extended memory address of last LB.
  302.       g.  Useful routines include:
  303.           1.)  SETCUR - reset cursor based on (R5,R6) and update
  304.                status
  305.                line if position has changed since last call.
  306.           2.)  PUTMSG - display 20 character message passed via R1.
  307.       h.  If the function you add, modifies any data in the SCB's, be
  308.           sure to turn on the SCBMOD and SCRMOD flags to insure that
  309.           the update and save routines recognize a file change
  310.           occurred.
  311.       i.  Assume nothing works and keep a backup copy of the editor
  312.           and any test files you are using.
  313.  
  314.   4.  Add key definition to F2 screen without exceeding 24 lines.
  315.  
  316.   5.  Test all changes very carefully since this program should be
  317.       considered complex.  The interaction between key routines and
  318.       the maintenance of the screen and memory control blocks during
  319.       scrolling, block operations, etc. is tricky to say the least.
  320.       Use the audit mode to verify that the new routine does not
  321.       destroy currency of the screen and extended memory data bases.
  322.  
  323. For release 2.0 of PC/370, the SEE editor was modified to use dynamic
  324. memory in the 370 address space instead of MS-DOS allocated extended
  325. memory accessed via the cross memory MVCS and MVCP moves.  The only
  326. other change was to start up editor in insert mode for new files.
  327.  
  328. C.  PRINTDOC print utility
  329.  
  330. The PRINTDOC.COM program requires path\filename as single parm and
  331. proceeds to print the specified file either on console or the standard
  332. print device with page control and optional headings controlled with
  333. embedded TITLE and EJECT commands.  For more information see the
  334. source code UTIL\PRINTDOC.ALC.
  335.  
  336. D.  T370 translate object code utility
  337.  
  338. The T370.COM program requires path\filename as single parm with
  339. optional trailing slash and one or more of the following parms:
  340.  
  341.   L - create listing file of the generated 370 OS/VS object file
  342.       (suffix is HEX).  Default is none.
  343.  
  344.   P - punch 370 object code file (suffix 370).  Default is on.
  345.  
  346. The input file specified must be an object file created by A370.EXE.
  347. For more information see the source UTIL\T370.ALC.
  348.  
  349.  
  350.  
  351.  
  352.